Configure LDAP using configuration files
You can make changes to how Splunk Enterprise authenticates with servers that run the Lightweight Directory Access Protocol (LDAP). The authentication.conf configuration file controls how Splunk Enterprise interacts with LDAP services for authentication.
Edit the authentication.conf
file in $SPLUNK_HOME/etc/system/local/
. For general information on editing configuration files, see About configuration files In the Admin Manual.
If you prefer to configure LDAP with Splunk Web, see Configure LDAP with Splunk Web.
How authentication.conf works with LDAP and LDAP strategies
When you change the authentication scheme on the Splunk platform from native to LDAP, you must specify at least one LDAP strategy for the instance to connect to when it performs authentication.
The authentication.conf file represents this as the authSettings
setting, where you specify at least one strategy, and a group of settings under a stanza for each strategy that you specify in the authSettings
setting. The stanza names for any LDAP strategies you specify must match the names that you specified in authSettings
. For example, if you configured authSettings=ad_ldap
, then there must be a stanza called ad_ldap
where the Splunk platform can look for settings and values for the ad_ldap
strategy.
When you configure an LDAP strategy stanza, you must specify a minimum of the following settings and values:
host
= <LDAP server name>port
= <LDAP port>groupBaseDN
= <string representation of the group base Distinguished Name (DN), ex: 'ou=Groups,dc=example,dc=com'>groupMemberAttribute
= <group entry attribute whose values are the group members, ex: 'uniqueMember'>groupNameAttribute
= <group entry attribute whose value stores the group name, ex: 'cn'>realNameAttribute
= <user entry attribute whose value is their real name, ex.: 'displayName' or 'cn'>userBaseDN
= <string representation of user base DN, ex: ou=People,dc=example,dc=com>userNameAttribute
= <user entry attribute whose value is the username, ex: 'uid'>
Either you or your LDAP administrator must provide the minimum setting values described here. There are additional settings that you can configure; see the authentication.conf specification file for those settings and their descriptions.
On Windows, there is no support for IPV6 address formats for the host
setting.
For examples of how to create authentication.conf
, see the authentication.conf spec file.
Configure multiple LDAP strategies
The Splunk platform can search across multiple LDAP servers, as described in How Splunk works with multiple LDAP servers. To configure multiple LDAP strategies, set the authSettings
setting to a comma-separated list of all strategies, in the order in which you want to query the strategies. Then, specify separate stanzas for each strategy.
Set the authentication type and configure LDAP strategy names and settings
This is a generic procedure for configuring authentication.conf for LDAP. Depending on your LDAP strategy settings, you might need to specify additional settings and values in the strategy-specific stanzas.
- Open a shell prompt.
- Change to the
$SPLUNK_HOME/etc/system/local
directory. - (Optional) Create the
authentication.conf
file if it does not already exist. - Open the
authentication.conf
file for editing. - Add the following lines to the file:
[authentication] authType = LDAP authSettings = <ldap_strategy1>,<ldap_strategy2>
<ldap_strategy#>
represents one or more LDAP strategies. You can separate multiple strategies with commas. - Configure a stanza for each of the LDAP strategies that you specified in the
authSettings
setting, with the stanza name matching the strategy that you specified.[authentication] authType = LDAP authSettings = ldap_strategy1 [ldap_strategy1]
- Add a minimum of the following lines for each strategy stanza:
[ldap_strategy] host = <LDAP server name> port = <LDAP port> groupBaseDN = <string representation of the group base Distinguished Name, ex: 'ou=Groups,dc=example,dc=com'> groupMemberAttribute = <group entry attribute whose values are the group members, ex: 'uniqueMember'> groupNameAttribute = <group entry attribute whose value stores the group name, ex: 'cn'> realNameAttribute = <user entry attribute whose value is their real name, ex.: 'displayName' or 'cn'> userBaseDN = <string representation of user base Distinguished Name, ex: ou=People,dc=example,dc=com> userBaseFilter = <user search filter, ex: (objectclass=*)> userNameAttribute = <user entry attribute whose value is the username, ex: 'uid'>
- Save the authentication.conf file and close it.
- Restart the Splunk platform.
Set authentication type and configure LDAP strategies with SSL
If you have enabled SSL for your LDAP strategy, you must edit two files: authentication.conf, where you set the authentication type to LDAP and configure your LDAP strategy, and ldap.conf, where you configure the Splunk platform to use your SSL certificates to connect to your LDAP strategy.
The ldap.conf file you use to enable your LDAP strategy is not stored with other Splunk Enterprise configuration files in the local or default configuration file directories. It must be stored in $SPLUNK_HOME/etc/openldap/. If you store it anywhere else, Splunk software is unable to set up your LDAP strategy.
You must also have already set up your SSL certificates on the instance where you want to use the LDAP authentication scheme. See Steps for securing your Splunk Enterprise deployment with TLS for additional information and procedures.
- Complete steps 1 to 7 of the previous procedure, "Set authentication type and configure LDAP strategy names and settings".
- For each LDAP strategy that you want to use SSL certificates to connect, add the following line in the strategy stanza:
[ldap_strategy1] ... SSLEnabled = 1
- Save the
authentication.conf
file and close it. - (Optional) Create the
ldap.conf
file if it does not already exist. - Add the following lines to the file:
TLS_REQCERT demand TLS_CACERT <path to your SSL certificate, for example: /opt/splunk/etc/auth/LDAProotcert.crt> TLS_CIPHER_SUITE <your cipher suite>
- Save the
ldap.conf
file in $SPLUNK_HOME/etc/openldap/ and close it. - Restart the Splunk platform.
Map LDAP groups to Splunk roles
To map an LDAP strategy group to a Splunk role, you must configure a roleMap
stanza in the authentication.conf
file for that strategy. Each strategy requires its own roleMap_
stanza. The following example maps LDAP groups in the "ldaphost1" strategy to Splunk roles. For each mapping, the syntax is <Splunk RoleName> = <LDAP group string>
.
[roleMap_ldaphost1] admin = SplunkAdmins itusers = ITAdmins
Map LDAP users to Splunk roles
If you need to map an LDAP user directly to a Splunk role, in the stanza for the LDAP strategy where you want to do the mapping:
- Set the value of the
groupBaseDN
setting to the value of theuserBaseDN
setting. - Set the values for the
groupMappingAttribute
,groupMemberAttribute
, andgroupNameAttribute
settings to the same value as theuserNameAttribute
setting.
For example:
[authentication] authType=LDAP authSettings=supportLDAP [supportLDAP] SSLEnabled = 0 bindDN = cn=Directory Manager bindDNpassword = ######### groupBaseDN = ou=People,dc=splunksupport,dc=com groupBaseFilter = (objectclass=*) groupMappingAttribute = uid groupMemberAttribute = uid groupNameAttribute = uid host = supportldap.splunksupport.com port = 389 realNameAttribute = cn userBaseDN = ou=People,dc=splunksupport,dc=com userBaseFilter = (objectclass=*) userNameAttribute = uid [roleMap_supportLDAP] admin = rlee;bsmith
Disable LDAP authentication and return to native authentication
If you configure LDAP authentication and decide later to return to using the default Splunk authentication scheme, the fastest way is to rename the authentication.conf
file to something else, for example, by renaming it to authentication.conf.disabled
, and restarting the Splunk platform.
Map LDAP groups to Splunk roles in Splunk Web | Map LDAP groups and users to Splunk roles using configuration files |
This documentation applies to the following versions of Splunk® Enterprise: 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1
Feedback submitted, thanks!